snapdragon

What is snapdragon?

The snapdragon npm package is a highly pluggable, low-level compiler for creating compilers and other text processing applications. It provides a robust framework for parsing, compiling, and rendering custom grammars in a structured way.

What are snapdragon's main functionalities?

Parsing

This feature allows you to define custom parsing rules. The code sample demonstrates how to create a simple text parser that recognizes sequences of lowercase letters.

const Snapdragon = require('snapdragon');
const snapdragon = new Snapdragon();
snapdragon.parser.use(function() {
  this.set('text', function() {
    const pos = this.position();
    const m = this.match(/^[a-z]+/);
    if (!m) return;
    return pos(this.node({type: 'text', val: m[0]}));
  });
});
const ast = snapdragon.parse('hello');
console.log(ast);

Compiling

This feature allows you to compile parsed input into a new form. The code sample shows how to compile a parsed abstract syntax tree (AST) into uppercase text.

const Snapdragon = require('snapdragon');
const snapdragon = new Snapdragon();
snapdragon.compiler.use(function(node) {
  if (node.type === 'text') {
    return node.val.toUpperCase();
  }
});
const ast = snapdragon.parse('hello');
const result = snapdragon.compile(ast).output;
console.log(result);

Rendering

This feature involves rendering the compiled output. The code sample illustrates how to render the output of a parsed AST, adding a space after each text node.

const Snapdragon = require('snapdragon');
const snapdragon = new Snapdragon();
snapdragon.renderer.use(function(node) {
  if (node.type === 'text') {
    this.emit(node.val + ' '); // add space after each text node
  }
});
const ast = snapdragon.parse('hello world');
const result = snapdragon.render(ast);
console.log(result);

Other packages similar to snapdragon

chevrotain

Chevrotain is a JavaScript parser building toolkit which is similar to snapdragon but focuses more on performance and ease of use for creating complex parsers without writing too much boilerplate code. It differs from snapdragon in that it provides a richer set of built-in features for defining grammars and performing lexical analysis.

nearley

Nearley is another parser toolkit that uses a different approach by leveraging grammar files written in a special format. It is similar to snapdragon in that it allows for the creation of custom parsers, but it automates more of the process and can handle more complex, ambiguous grammars.

pegjs

PEG.js is a simple parser generator that allows you to create parsers directly from a string representation of a Parsing Expression Grammar. It is similar to snapdragon in its purpose but differs in that it generates parsers from a high-level description rather than requiring manual definition of parsing behavior.

README

snapdragon

Fast, pluggable and easy-to-use parser-renderer factory.

Install

Install with npm:

$ npm install --save snapdragon

Created by jonschlinkert and doowb.

Features

• Bootstrap your own parser, get sourcemap support for free
• All parsing and compiling is handled by simple, reusable middleware functions
• Inspired by the parsers in pug and css.

History

v0.5.0

Breaking changes

Substantial breaking changes were made in v0.5.0! Most of these changes are part of a larger refactor that will be finished in 0.6.0, including the introduction of a Lexer class.

• Renderer was renamed to Compiler
• the .render method was renamed to .compile
• Many other smaller changes. A more detailed overview will be provided in 0.6.0. If you don't have to time review code, I recommend you wait for the 0.6.0 release.

Usage examples

var Snapdragon = require('snapdragon');
var snapdragon = new Snapdragon();

Parse

var ast = snapdragon.parser('some string', options)
  // parser middleware that can be called by other middleware
  .set('foo', function () {})
  // parser middleware, runs immediately in the order defined
  .use(bar())
  .use(baz())

Render

// pass the `ast` from the parse method
var res = snapdragon.compiler(ast)
  // compiler middleware, called when the name of the middleware
  // matches the `node.type` (defined in a parser middleware)
  .set('bar', function () {})
  .set('baz', function () {})
  .compile()

See the examples.

Getting started

Parsers

Parsers are middleware functions used for parsing a string into an ast node.

var ast = snapdragon.parser(str, options)
  .use(function() {
    var pos = this.position();
    var m = this.match(/^\./);
    if (!m) return;
    return pos({
      // `type` specifies the compiler to use
      type: 'dot',
      val: m[0]
    });
  })

AST node

When the parser finds a match, pos() is called, pushing a token for that node onto the ast that looks something like:

{ type: 'dot',
  val: '.',
  position:
   { start: { lineno: 1, column: 1 },
     end: { lineno: 1, column: 2 } }}

Renderers

Renderers are named middleware functions that visit over an array of ast nodes to compile a string.

var res = snapdragon.compiler(ast)
  .set('dot', function (node) {
    console.log(node.val)
    //=> '.'
    return this.emit(node.val);
  })

Source maps

If you want source map support, make sure to emit the position as well.

var res = snapdragon.compiler(ast)
  .set('dot', function (node) {
    return this.emit(node.val, node.position);
  })

Docs

Parser middleware

A parser middleware is a function that returns an abject called a token. This token is pushed onto the AST as a node.

Example token

{ type: 'dot',
  val: '.',
  position:
   { start: { lineno: 1, column: 1 },
     end: { lineno: 1, column: 2 } }}

Example parser middleware

Match a single . in a string:

1. Get the starting position by calling this.position()
2. pass a regex for matching a single dot to the .match method
3. if no match is found, return undefined
4. if a match is found, pos() is called, which returns a token with:

• type: the name of the [compiler] to use
• val: The actual value captured by the regex. In this case, a .. Note that you can capture and return whatever will be needed by the corresponding [compiler].
• The ending position: automatically calculated by adding the length of the first capture group to the starting position.

Renderer middleware

Renderers are run when the name of the compiler middleware matches the type defined on an ast node (which is defined in a parser).

Example

Exercise: Parse a dot, then compile it as an escaped dot.

var ast = snapdragon.parser('.')
  .use(function () {
    var pos = this.position();
    var m = this.match(/^\./);
    if (!m) return;
    return pos({
      // define the `type` of compiler to use
      type: 'dot',
      val: m[0]
    })
  })

var result = snapdragon.compiler(ast)
  .set('dot', function (node) {
    return this.emit('\\' + node.val);
  })
  .compile()

console.log(result.output);
//=> '\.'

API

Parser

Create a new Parser with the given input and options.

Params

• input {String}
• options {Object}

.define

Define a non-enumberable property on the Parser instance.

Example

parser.define('foo', 'bar');

Params

• key {String}: propery name
• val {any}: property value
• returns {Object}: Returns the Parser instance for chaining.

Set parser name with the given fn

Params

• name {String}
• fn {Function}

Get parser name

Params

• name {String}

Push a token onto the type stack.

Params

• type {String}
• returns {Object} token

Pop a token off of the type stack

Params

• type {String}
• returns {Object}: Returns a token

Return true if inside a stack node. Types are braces, parens or brackets.

Params

• type {String}
• returns {Boolean}

Example

parser.isType(node, 'brace');

Params

• node {Object}
• type {String}
• returns {Boolean}

.define

Define a non-enumberable property on the Compiler instance.

Example

compiler.define('foo', 'bar');

Params

• key {String}: propery name
• val {any}: property value
• returns {Object}: Returns the Compiler instance for chaining.

About

Related projects

• braces: Fastest brace expansion for node.js, with the most complete support for the Bash 4.3 braces… more | homepage
• expand-brackets: Expand POSIX bracket expressions (character classes) in glob patterns. | homepage
• extglob: Convert extended globs to regex-compatible strings. Add (almost) the expressive power of regular expressions to… more | homepage
• micromatch: Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch. | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Contributors

Commits	Contributor
106	jonschlinkert
2	doowb

Building docs

(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)

To generate the readme and API documentation with verb:

$ npm install -g verb verb-generate-readme && verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2016, Jon Schlinkert. Released under the MIT license.

---

This file was generated by verb-generate-readme, v0.1.31, on October 10, 2016.